feat(reviewer): checksum-pinned reviewer sandbox image and launcher (PR 2 of #425) - #428

What this builds

PR 2 of #425: section A's image and launcher — the parts that do not depend on PR 1's plugin.

What review-build-ok means. It is advisory evidence for the reviewer, not a merge gate: CI remains the gate on every PR. The boundary this PR holds is that no credential and no host access are reachable from the review. How well a review build predicts CI is best effort — features the launcher cannot reproduce faithfully are refused, and the fidelity limits that remain are listed below. One integrity property is conditional on the host and not yet verified: the host assignment (below) is immutable to the review only if the reviewer host denies same-user process-memory writes (#436).

• The image (docker/reviewer/Dockerfile, linux/amd64): FROM debian:bookworm-slim pinned by digest, with OpenClaw's sandbox package set (bash, ca-certificates, curl, git, jq, python3, ripgrep) plus Node, Bun, a gh with no credential of its own and the launcher's js-yaml, each at an exact version verified against a checksum from the trusted table. No entrypoint; CMD ["sleep", "infinity"]. Default HOME, TMPDIR and caches point under /tmp/review (a tmpfs in OpenClaw's run model). No credentials, no configured credential helpers.
• The trusted runtime table (docker/reviewer/runtime-matrix.json): base digest and platform, exact runtime versions and checksums, the launcher's js-yaml pin (the version and integrity bun.lock pins), and the image matrix. Maintained here and installed on the host; the reviewed checkout can neither extend it nor choose a download source.
• The resolver (scripts/reviewer/resolve-runtime.mjs): packageManager, engines, .nvmrc, .node-version, .bun-version, .tool-versions and every planned job's pins resolve to ONE matrix image with npm-semver range semantics, or are refused by name (invalid-declaration, ambiguous, conflicting, out-of-matrix). An out-of-matrix refusal names the missing image by its requirements, e.g. missing image: node >=25 with bun 1.3.10.
• The planner (scripts/reviewer/ci-job.mjs): bounds the workflow (256 KiB; 50,000 YAML nodes counting every alias use; 32 levels), requires printable-ASCII keys and a pull_request trigger covering the base branch, and plans the host-named job with the jobs it needs. Every job must begin with actions/checkout and run on ubuntu-latest or ubuntu-24.04 (the labels these repositories use; CI shows ubuntu-latest resolving to ubuntu-24.04). timeout-minutes on the job and on run: steps is carried for enforcement; on a skipped uses: step it is refused (how the real action behaves at that limit cannot be reproduced). It skips checkout (first step only; fetch-depth 1 or 0), setup-bun and setup-node (an exact version, which becomes a verified pin), socketdev (firewall-free), cache (path and key required; a miss may not fail the job) and upload-artifact (path required; a missing file may not fail the job; a valid name unique in the workflow) — each only at a reviewed commit SHA (release tags confirmed, action.yml inputs read), with every input the real action needs, and only with literal values whose skip is equivalent. It refuses any other action, ref or input; a ${{ }} expression anywhere it would have to be evaluated — scripts, env values, working directories, runner labels, timeouts and every input of a skipped action, since a skipped action never evaluates it (a cache key such as ${{ runner.os }},bad, which the real action rejects, is refused); the only expressions accepted are if: conditions that are exactly success() or always(). It also refuses other if: conditions, continue-on-error, matrices, containers, non-bash shells, launcher-owned env keys, and credential-shaped or config-redirecting env (GH_TOKEN, *_TOKEN, *_SECRET, *_KEY, GIT_*, NPM_CONFIG_*, SSH_*, NODE_OPTIONS, BASH_ENV, LD_*, proxies, …).
• The launcher (/opt/reviewer/bin/reviewer-launch; build mode takes no arguments and always builds /workspace; --self-check is the only other mode): takes the workflow, job and base branch only from the environment the host gave the sandbox at creation (REVIEWER_CI_WORKFLOW, REVIEWER_CI_JOB, REVIEWER_CI_BASE in sandbox.docker.env, read from the container init's environment) and refuses a caller that passes different values — which makes the assignment immutable to the review only if the host denies same-user process-memory writes, not yet verified (reviewer sandbox: check and enforce the same-user process isolation the launcher's assignment relies on #436); refuses symlinked lockfiles and symlinked directories in the worktree; resolves the declarations (read with size bounds, inside the worktree) and pins to ONE image and refuses unless it is THIS image; builds the child env from an allowlist with a fixed PATH; runs the image's own node and bun at fixed paths to verify their versions. Then, job by job in dependency order, with CI's gating: removes what earlier jobs of the build created; gives the job a fresh HOME/TMPDIR/cache root; refuses a worktree whose effective git configuration leaves the safe baseline — an allowlist of the keys a plain clone and an identity write; core.fsmonitor, core.hooksPath, core.pager, core.editor, protocol.*, uploadpack.*, url.*.insteadOf, credential helpers, auth headers and every other key are refused by key, never by value; the values of remote.<name>.url and .fetch are the host clone's and are not approved, only pinned — or whose repository holds hooks; refuses unless the worktree passes the clean-clone check: HEAD and every remote URL and fetch refspec unchanged since the first job, no tracked file carrying the assume-unchanged or skip-worktree bit, git status (replace objects ignored) reporting no modified, untracked or ignored path, and history shaped as fetch-depth asks (shallow one-commit without tags, or full for fetch-depth: 0) — not a byte comparison with a host-pinned commit; runs each run: step under /bin/bash --noprofile --norc -eo pipefail in its own process group after re-checking its effective environment and that its resolved working directory stays inside the worktree; kills a run: step at its timeout-minutes and the job's steps at the job's (default 360), and kills what the job left running when it ends. After every job it refuses symlinked lockfiles, symlinked directories and any lockfile change. review-build-ok only if every job in the closure ran and every step exited 0.
• The CI job (reviewer-image): builds every matrix image and runs the A2/A3/A9 checks, with build-path fixtures run the OpenClaw way on depth-1 clones: out-of-matrix and other-image pins, a caller naming another job, a --workspace argument, impostor binaries on the caller's PATH, an enforced run: step timeout-minutes, a worktree that fails the clean-clone check, a git core.fsmonitor, a worktree git auth header and a workflow GH_TOKEN; then a9-red-proofs.sh requires the A9 checks to FAIL on five derived images carrying planted fake credentials.

Decisions

• Scope (Flint): review-build-ok is evidence, not a gate; the PR must hold "no credential and no host access reachable from the review". CI-fidelity findings are fixed when cheap, otherwise documented and filed.
• Platform: linux/amd64 only (the reviewer VMs are x86_64, Docker 29.1.3, OpenClaw 2026.8.1). Pinned in the Dockerfile FROM, the build script and the matrix; arm64 is out of scope.
• Base image: debian:bookworm-slim pinned by digest and labelled as such. This deviates from spec A's "OpenClaw sandbox base", accepted because no digest-pinnable OpenClaw sandbox base is published: OpenClaw 2026.8.1's documented sandbox build is a local FROM debian:bookworm-slim (floating tag) with bash, ca-certificates, curl, git, jq, python3 and ripgrep; this image pins that base by digest and carries the same packages.
• Run model: OpenClaw 2026.8.1 creates sandboxes as docker create --init --read-only --tmpfs /tmp --tmpfs /var/tmp --tmpfs /run --network none --cap-drop ALL --security-opt no-new-privileges --workdir /workspace … <image> sleep infinity without overriding the entrypoint. So the image has no entrypoint, and the launcher is an explicit command that creates its own hermetic directories.
• Host binding: the assignment is read from the sandbox's creation environment, not a bind-mounted file: OpenClaw 2026.8.1 allows bind sources only inside the workspace roots, which are mounted writable, unless dangerouslyAllowExternalBindSources is set. Its integrity against the review depends on the host denying same-user process-memory writes; enforcing and testing that on the reviewer hosts is reviewer sandbox: check and enforce the same-user process isolation the launcher's assignment relies on #436, and until it lands the claim is conditional.
• Host worktree contract: the host mounts a fresh clone of the assigned head with its git metadata inside it — depth 1 without tags for checkout's default fetch, a full clone for fetch-depth: 0.
• timeout-minutes: enforced on the job and on run: steps, not refused (flair's workflows use it); refused on a skipped uses: step.
• Expressions in skipped-action inputs: refused in every input, not only the required ones: restore-keys has the same failure rule as key (actions/cache rejects any key over 512 characters or containing a comma), and a skipped action never evaluates either.
• Symlinks: lockfile symlinks and directory symlinks are refused before the build and after every job; lockfile drift is not hashed through links.
• No registry in this slice: the host builds the image from the pinned Dockerfile at install time and records its local image id in host config (sandbox.docker.image: "sha256:…"). Builds on different hosts are not claimed to produce the same image id (apt packages are not pinned); cross-host reproducibility is a follow-up.
• This repository declares engines.node: "22.x" in package.json, the Node major its CI runs, so it resolves to reviewer-node22-bun1310.

Tests

The cli suite runs the four reviewer test files: the planner, the resolver, the A3 diff filter and the launcher end to end with real bash and real git on depth-1 clones of a temporary source repository. Every round-7 control has a test that fails on 38ac74d and passes here. Mutation-checked: the round-2, round-5 and round-6 sets re-run plus every round-7 control (break → red; restore by copy → green); the exact table and counts are in the round-7 notes. The image-level checks, the host-binding, timeout, fresh-clone, git-baseline and credential fixtures, and the A9 red proofs run only in the reviewer-image job.

Known limits

Trust boundary (host integration, PR 3):

• The assignment is read from the container init's environment, which runs as the same user as the sandbox. Its integrity relies on the deployed sandbox denying same-user process-memory writes (no ptrace capability; Yama ptrace_scope ≥ 1). That host-integration check is not in place (reviewer sandbox: check and enforce the same-user process isolation the launcher's assignment relies on #436): until it lands, "a caller cannot change the assignment" holds against a caller that sets its own environment, not against one that can write the init process's memory.

CI fidelity (review-build-ok may disagree with CI):

• Jobs of a needs closure share one worktree. Before each job the launcher removes what earlier jobs created and applies the clean-clone check; what that check cannot see carries over — a change git status does not report (for example a line-ending-only change under a text attribute) and .git/ state beyond HEAD, the index bits and the remote settings (reviewer sandbox: a fresh isolated tree per needs job #435: an independent tree per job at a host-pinned commit).
• On pull_request, CI checks out the merge of the head into the base; the review builds the assigned head.
• CI's runner carries its own Node where a workflow does not pin one (22.23.2 today); the review uses the matrix image's (22.22.1).
• Socket Firewall is not reproduced (sfw runs the command unwrapped); cache restores never happen (a cold build); artifact uploads are not performed.
• Each step runs with pipefail; CI's default for an unspecified shell is bash -e {0}.
• Only a pull_request trigger with exact branch names is evaluated; the assignment is static per reviewer, so a review into another base is refused.
• The "no credential" statements cover the image, the environments the launcher builds and the worktree's git configuration; a credential that repository code itself supplies is outside them.
• OpenClaw's default /tmp tmpfs is noexec; a suite that executes files from TMPDIR needs /tmp:exec in the reviewer's sandbox config (A15).

What PR 3 will add

• A8 (sandbox access boundaries) and A10 (host/container contrast): the mount/filesystem/process/gateway-tool/network policy checks and the gateway-process lane. Both need PR 1's plugin and land after feat(openclaw-github-review): host-side github_review tool (PR 1 of #425) #427 merges. The same-user process-memory check above belongs there.

Refs #425

🤖 Generated with Claude Code